/**
 * Copyright (c) 2010 Simple Graph Tools contributors. All rights reserved.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * $Id$
 */
package org.sgt.transformations;

import java.util.Map;


/**
 * The ITransformation interface (generically specifies a {@link ITransformation}.
 * A transformation transforms the input(s) into output(s) making use of parameter(s).
 * The sequencing of the calls to the Transformation object is the following :<UL>
 * <LI>{@link #setInputs(Map)} which sets the objects to be transformed.</LI>
 * <LI>{@link #setParameters(Map)} which sets transformation parameters.</LI>
 * <LI>{@link #prepare()} which is doing the preparation work for the transformation.</LI>
 * <LI>{@link #process()} which is doing the actual transformation work.</LI>
 * <LI>{@link #postProcess()} which is doing the optional post transformation work.</LI>
 * <LI>{@link #getOutputs()} which returns the {@link Map} of transformation's outputs.</LI>
 * </UL>
 * @author BUTTIGHOFFER-A
 *
 */
public interface ITransformation {
	
	/**
	 * Preparation of the transformation :
	 * <UL>
	 * <LI>
	 * loading and checking inputs and parameters.
	 * </LI>
	 * </UL>
	 * 
	 * @throws TransformationException in case the preparation failed.
	 */
	public void prepare() throws TransformationException;
	
	/**
	 * Performs the transformation :
	 * <UL>
	 * <LI>
	 * produces outputs from inptus and parameters
	 * according to transformation's specificities.
	 * </LI>
	 * </UL>
	 * 
	 * @throws TransformationException in case the transformation failed.
	 */
	public void process() throws TransformationException;
	
	/**
	 * Post processing if needed:
	 * <UL>
	 * <LI>
	 * updates inputs and outputs
	 * </LI>
	 * <LI>
	 * saves inputs/outputs, ...
	 * </LI>
	 * </UL>
	 * 
	 * @throws TransformationException
	 */
	public void postProcess() throws TransformationException;
	
	/**
	 * Inputs setter.
	 * @param inputs the String-Object inputs map.
	 */
	public void setInputs(Map<String, Object> inputs);
	
	/**
	 * Getter for inputs.
	 * @return the String-Object inputs map (may be null or empty).
	 */
	public Map<String, Object> getInputs();

	/**
	 * Getter for outputs.
	 * @return the String-Object outputs map (may be null or empty).
	 */
	public Map<String, Object> getOutputs();

	/**
	 * Parameters setter.
	 * @param params the transformation's parameters String-Objectmap.
	 * @throws TransformationException 
	 */
	public void setParameters(Map<String, Object> params) throws TransformationException;
	
	/**
	 * Getter for Parameters.
	 * @return the String-Object transformation's parameters
	 * map (may be null or empty).
	 */
	public Map<String, Object> getParameters();

}
